Description

A short while ago I submitted a PR for a new Number macro called pairs(). However, while using it in a production app I realized that it didn't perform exactly how I intended because it was missing an important argument: the starting value.

This PR introduces a new $start argument, which improves the behavior of the method to match expectations. Before, the $offset argument was being reused for both but this was conflating things and resulted in weird offsets. With a distinct $start argument both the initial value and the increment between pairs can be individually controlled.

Note: This is a breaking change due to a new 3rd argument!

Before

$output = Number::pairs(2500, 1000, 1); // Start at 1, offset also 1

// [[1, 1000], [1001, 2000], [2001, 2500]]

$output = Number::pairs(2500, 1000, 0); // Start at 0 offset also 0

// [[0, 1000], [1000, 2000], [2000, 2500]]

While this looks fine, you'll notice that you can't get the values to end in 999, ie. [1, 999] or [0, 999]. This means that your offset/pagination value must always start with 1, which may be incorrect.

After

$output = Number::pairs(2500, 1000, 1, 0); // Start at 1, offset 0

// [[1, 1001], [1001, 2001], [2001, 2500]]

$output = Number::pairs(2500, 1000, 1, 1); // Start at 1, offset 1

// [[1, 1000], [1001, 2000], [2001, 2500]]

$output = Number::pairs(2500, 1000, 0, 0); // Start at 0, offset 0

// [[0, 1000], [1000, 2000], [2000, 2500]]

$output = Number::pairs(2500, 1000, 0, 1); // Start at 0, offset 1

// [[0, 999], [1000, 1999], [2000, 2500]]

Now, starting value and offsets are distinct allowing for the proper pairing.